/*-------------------------------------------------------------------------
 *
 * arrayaccess.h
 *	  Postgres数组逐元素访问的声明。
 *
 * Portions Copyright (c) 1996-2022, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994, Regents of the University of California
 *
 * src/include/utils/arrayaccess.h
 *
 *-------------------------------------------------------------------------
 */
#ifndef ARRAYACCESS_H
#define ARRAYACCESS_H

#include "access/tupmacs.h"
#include "utils/array.h"


/*
 * 用于迭代平面或扩展数组元素的函数。
 * 这些需要一个状态结构 "array_iter iter"。
 *
 * 使用 "array_iter_setup(&iter, arrayptr);" 来准备迭代，以及
 * "datumvar = array_iter_next(&iter, &isnullvar, index, ...);" 将下一个元素提取
 * 到 datumvar/isnullvar。
 * "index" 必须是从零开始的元素编号；我们让调用者提供
 * 这个值，因为调用者通常在计数元素。尽管如此，
 * 这些函数只能顺序获取元素。
 */

typedef struct array_iter
{
	/* datumptr 为 NULL 与否指示我们是平面数组还是扩展数组 */

	/* 使用扩展数组时的字段 */
	Datum	   *datumptr;		/* 指向 Datum 数组的指针 */
	bool	   *isnullptr;		/* 指向 isnull 数组的指针 */

	/* 当我们有一个平面数组时使用的字段 */
	char	   *dataptr;		/* 数据区域中的当前位置 */
	bits8	   *bitmapptr;		/* nulls 位图的当前字节，或 NULL */
	int			bitmask;		/* nulls 位图中当前位的掩码 */
} array_iter;


static inline void
array_iter_setup(array_iter *it, AnyArrayType *a)
{
	if (VARATT_IS_EXPANDED_HEADER(a))
	{
		if (a->xpn.dvalues)
		{
			it->datumptr = a->xpn.dvalues;
			it->isnullptr = a->xpn.dnulls;
			/* 我们必须填充所有字段以防止编译器警告 */
			it->dataptr = NULL;
			it->bitmapptr = NULL;
		}
		else
		{
			/* 处理嵌入于扩展数据项中的平面数组 */
			it->datumptr = NULL;
			it->isnullptr = NULL;
			it->dataptr = ARR_DATA_PTR(a->xpn.fvalue);
			it->bitmapptr = ARR_NULLBITMAP(a->xpn.fvalue);
		}
	}
	else
	{
		it->datumptr = NULL;
		it->isnullptr = NULL;
		it->dataptr = ARR_DATA_PTR((ArrayType *) a);
		it->bitmapptr = ARR_NULLBITMAP((ArrayType *) a);
	}
	it->bitmask = 1;
}

static inline Datum
array_iter_next(array_iter *it, bool *isnull, int i,
				int elmlen, bool elmbyval, char elmalign)
{
	Datum		ret;

	if (it->datumptr)
	{
		ret = it->datumptr[i];
		*isnull = it->isnullptr ? it->isnullptr[i] : false;
	}
	else
	{
		if (it->bitmapptr && (*(it->bitmapptr) & it->bitmask) == 0)
		{
			*isnull = true;
			ret = (Datum) 0;
		}
		else
		{
			*isnull = false;
			ret = fetch_att(it->dataptr, elmbyval, elmlen);
			it->dataptr = att_addlength_pointer(it->dataptr, elmlen,
												it->dataptr);
			it->dataptr = (char *) att_align_nominal(it->dataptr, elmalign);
		}
		it->bitmask <<= 1;
		if (it->bitmask == 0x100)
		{
			if (it->bitmapptr)
				it->bitmapptr++;
			it->bitmask = 1;
		}
	}

	return ret;
}

#endif							/* ARRAYACCESS_H */
